Repository navigation
feat(cli): site archive container for export and import (#47, step 1) - #129
Merged
Merged
Conversation
RFC-0039 rollout step 1: the .cloudhal container that `cloudhal export` will write and `cloudhal import` read. A POSIX ustar stream (regular files only, fixed modes, zero times, 10240-byte records) compressed with gzip at a fixed level and a fixed OS byte, holding manifest.json first and then project.json, nodes/snapshots/blobs NDJSON parts of at most 8 MiB, media/<sha256> and ledger.ndjson in one fixed order. The reader treats the file as untrusted input: a closed list of paths, no links, devices or extended headers, header checksums, every file checked against the manifest's size and SHA-256 (media also against its name), row counts, caps on the manifest, parts, media, total decompressed bytes and entry count, and no data after the tar or gzip end. Parts reach the caller only once verified; media bodies stream and fail at their end on a mismatch. The writer streams media and verifies them on the way, and writes to a temporary file that is renamed only when complete. RFC-0039 invariant 7 and ADR-0041 rule 6 are amended: gzip output differs between zlib builds, so identical .cloudhal bytes hold for the same Node/zlib build, while the tar inside and every manifest SHA-256 are identical on every platform. No command yet; `cloudhal export` comes next. Refs #47 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Madraka <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
This is step 1 of RFC-0039's rollout for #47: the
.cloudhalcontainer thatcloudhal export(step 2) will write andcloudhal import(steps 3–4) will read. It adds no command yet and no user-visible change, so there is no changeset. The code lives inpackages/cli/src/archive/, is Node-only, and no Worker imports it.manifest.jsonfirst, thenproject.json, thenodes|snapshots|blobs/NNNN.ndjsonparts (a new part every 8 MiB),media/<sha256>sorted by hash, andledger.ndjson.createdAtandcreatedByfrom the caller, never from the clock. Step 2 passes the site's newest row timestamp and the CLI version..., absolute paths, backslashes and malformed names are refused. Links, devices, directories and pax/GNU extended headers are refused too.MAX_MEDIA_PUT), total decompressed bytes and the number of entries.schemaVersionis refused with a message naming thecreatedByversion.RFC / ADR amendment, please review
Invariant 7 promised identical bytes for an unchanged site, but gzip output differs between zlib builds. We reproduced this: Homebrew's Node and the official Chromium-zlib Node give different
.gzbytes for the same input.The amendment in RFC-0039 (invariant 7, rollout step 5) and ADR-0041 (rule 6) says:
.cloudhalbytes hold for the same Node/zlib build;Avoiding the difference entirely would need a pure-JS deflate dependency. The step 5 demo archive is regenerated on one pinned Node, or compared through its tar.
Verification (local)
vitest run test/archive-inpackages/cli: 6 files, 117 tests. They cover:tar -tzf/-xzfgive the same paths and bytes.pnpm --filter @cloudhal/cli typecheck,tsc -p tsconfig.build.json(declarations), repo-widebiome checkandpnpm size:checkpass.Checklist
pnpm checkandcargo test --workspacepass locally. Ran the pieces that cover this change (biome, size, CLI typecheck and declarations, the archive tests). There is no Rust or contract change, and CI runs the full set.cloudhal export) adds the changeset.git commit -s, DCO)Refs #47
🤖 Generated with Claude Code